Toddle's API panel includes many advanced features, which are located under the advanced tab.
Redirect rules
Redirects can help or even be necessary in several situations:
When a page requires the user to be authenticated, but the user is not logged in
If a page is not available in the user's language/country
If a page has been moved to a new location
To support these situations, we can use a list of rules to determine the final URL the user will be redirected to. The rules are applied in order, and the first rule that matches the user's situation will be used to determine the final URL.
A redirect can happen server-side or client-side (before or after rendering). Depending on the situation, redirecting the server side is often preferable to ensure the user doesn't see a page flash before they get redirected to another page. Client-side redirects are often helpful when a user's session times out while working on a page in your application.
APIs evaluated during SSR will allow server-side redirects, which essentially means that the user will never see the page they requested but will be redirected before anything is rendered. Please note that server-side redirects are only supported on a paid plan.
A simple example would be to add a redirect rule that redirects the user to a `/login` page if the API request returns a 401 status code. This way, the user will be redirected to the login page if not authenticated. To create a redirect rule:
Go to the "Advanced" section of your API request.
Add a new rule.
Give the rule a name.
Add a formula that will return a URL/path to redirect if the rule matches.
Below is an example formula that will redirect the user if the API returns a 401 status code.
The' Is Server' formula can differentiate between client-side and server-side redirects.
When you request an API in the API window, the "debug" section of the response contains information about its redirect behavior.
Server-side rendering (SSR)
You can specify per API whether an API request should be evaluated during server-side rendering (SSR). Evaluating API requests during SSR is ideal when you want to render content based on an API's response immediately when a page is loaded.
API requests evaluated during SSR will not be fetched on the client unless parameters are changed on the client (for instance, if the user applies a filter to a search request). This means you should only see a single request to your backend for a single page load.
SSR-enabled API requests have a few limitations:
They must be set to auto-fetch to run during SSR
They must return text or JSON data (Content-Type header should be similar to text/plain or application/json)
If you have a slow API, you can disable SSR for that API to speed up the initial page load. To know whether an API request is slow, you can inspect its response time in the API dialog. If it takes more than a few hundred milliseconds, you should consider disabling SSR for that API and loading it after the page has been rendered.
Proxy
API requests are passed through toddle's global edge network by default instead of going directly from the user's browser to the API. This practice is known as proxying, and the node in the edge network through which the requests are passed is called a proxy. There are a few reasons why this is beneficial.
Enabling access tokens to be stored securely. Storing an access token in a secure cookie is the safest approach. Still, since the cookie is not accessible from within the browser, requests must be passed through our proxy to set the appropriate authentication headers. The toddle proxy allows cookie values to be used in the URL or headers. The toddle proxy never reads the request/response body.
Avoiding CORS issues. CORS, or Cross-Origin Resource Sharing, happens when a single website fetches data from several domains. CORS is a vital part of the web in many ways, but it also introduces many security headaches. For that reason, browsers do not allow CORS requests without first checking that the server allows such requests. Because your application runs on the same node we proxy your API requests through, this is no longer an issue.
The "Advanced" section of the API dialog allows you to control whether an API request should be proxied.
Response parsing
By default, toddle tries to parse an API's response based on its Content-Type header. Sometimes, you might want to override this behavior and always parse the response as JSON (or other types). You can pick another parse option in the Response parsing section. The supported options are:
Sometimes, if an API response is taking too long, you want to cancel it—especially during SSR. For each API request, you can set a timeout. If the API request takes longer than the timeout, it will be canceled, and you will get an error instead. One use case for this is to prevent SSR from hanging if an API request takes too long. You will then need to rerun the request on the client side.
The timeout is specified in milliseconds and can be differentiated between client and server using the Is Server formula.
Debounce
You may want to limit the number of frequent API requests to avoid hitting rate limits or spending too much resources on your backend.
One way to do this is to use debouncing. Specifying a debounce timer will ensure an API is only called after a certain amount of time has passed since the last call. The timer is reset if another call is made before the time has passed.
This is especially useful for API requests that rely on an input (a filter or search bar, for instance) where the user may be typing quickly, and you don't want to request every keystroke. Debouncing is specified in milliseconds.
Error definition
You can work with the "data" or "error" from an API request in toddle. By default, we put the response in the "error" section if the response's status code is 400+. For some applications/APIs, though, it's sometimes helpful to modify this behavior. For a GraphQL response, for instance, errors are usually declared in the "body" of the response - not in the response's status code.
To customize this behavior, you can add an "Is error" formula to indicate whether a response should be treated as an error. If the return value is truthy, the response will be available in the "error" section - otherwise, in the "data" section of the response.
